package com.gobang.service;

import com.gobang.domain.entity.MatchQueueEntry;

import java.util.List;

/**
 * 匹配算法接口
 * 定义匹配算法的核心方法
 *
 * @author gobang-team
 * @since 1.0.0
 */
public interface MatchAlgorithm {

    /**
     * 查找匹配
     * 为指定用户在队列中查找合适的对手
     *
     * @param currentUser 当前用户队列条目
     * @param waitingQueue 等待队列中的其他用户
     * @return 匹配的对手，如果未找到返回null
     */
    MatchQueueEntry findMatch(MatchQueueEntry currentUser, List<MatchQueueEntry> waitingQueue);

    /**
     * 批量匹配
     * 对整个等待队列进行批量匹配处理
     *
     * @param waitingQueue 等待队列
     * @return 匹配对列表，每个元素包含两个匹配的用户
     */
    List<MatchPair> batchMatch(List<MatchQueueEntry> waitingQueue);

    /**
     * 计算匹配度
     * 计算两个用户之间的匹配度分数
     *
     * @param user1 用户1
     * @param user2 用户2
     * @return 匹配度分数，分数越高表示匹配度越好
     */
    double calculateMatchScore(MatchQueueEntry user1, MatchQueueEntry user2);

    /**
     * 是否匹配
     * 判断两个用户是否满足匹配条件
     *
     * @param user1 用户1
     * @param user2 用户2
     * @return 是否匹配
     */
    boolean isMatch(MatchQueueEntry user1, MatchQueueEntry user2);

    /**
     * 匹配对内部类
     */
    class MatchPair {
        private final MatchQueueEntry user1;
        private final MatchQueueEntry user2;
        private final double matchScore;

        public MatchPair(MatchQueueEntry user1, MatchQueueEntry user2, double matchScore) {
            this.user1 = user1;
            this.user2 = user2;
            this.matchScore = matchScore;
        }

        public MatchQueueEntry getUser1() {
            return user1;
        }

        public MatchQueueEntry getUser2() {
            return user2;
        }

        public double getMatchScore() {
            return matchScore;
        }

        @Override
        public String toString() {
            return String.format("MatchPair{user1=%d, user2=%d, score=%.2f}", 
                    user1.getUserId(), user2.getUserId(), matchScore);
        }
    }
} 